fix(wizard): pin workflow persist to the source workspace - #134

Resumen ejecutivo

Esta primera sección está pensada para project managers y revisores no técnicos. Mantén el detalle técnico completo más abajo.

Qué cambia

Los checkpoints del Wizard ya no pueden guardarse en la carpeta de destino cuando el usuario cambia de workspace a mitad de un guardado en conflicto.

Para qué sirve

Evita que un workflow en curso de la carpeta A se mezcle o sobrescriba los workflows persistidos de la carpeta B.

Impacto para el usuario

Si cambia de carpeta de salida mientras un workflow del Wizard reintenta un guardado, B conserva sus propios checkpoints y A sigue recibiendo el suyo.

Riesgo

• Bajo
• Medio
• Alto

Estado

• En desarrollo
• Listo para revisión
• Bloqueado por CI o revisión
• Requiere migración o acción manual

Summary

WizardWorkflowRuntime.persist() cloned the in-memory collection correctly, but CAS conflict retries called load(this.workspace) / save(this.workspace) against the live pointer. open() rebinds that pointer immediately, so a folder switch during the retry merged the source checkpoint into the destination .wizard-workflows-v1.json and then replaced the in-memory collection.

This is distinct from the rejected conversation-CAS bug (hocuspocus#48 / PR #122). Conversations already pin writes by workspace; workflow checkpoints did not.

Overview

Concrete trigger:

1. Workspace A has a waiting Wizard workflow; workspace B already has its own checkpoint.
2. A task event updates A's workflow and persist() hits a CAS conflict (second tab, concurrent workflow save, or overlapping persist).
3. While that first save is in flight, the footer output folder changes to B and the panel calls open('workspace-b').
4. Before this fix, the retry loaded B, mergeCollections'd A's workflows into B, and saved the mix to B. A's latest state was also lost.

The fix pins targetWorkspace / openSequence at the start of persist(). Retries always read/write that workspace. In-memory collection updates are applied only if the runtime still owns that open. persistAndEmit no longer throws Workflow does not exist after a switch.

Detailed changes

Backend

No backend changes.

UI and Wizard

• ui/src/features/agent/wizardWorkflowRuntime.ts: pin persist target; guard in-memory updates; tolerate emit after switch.
• ui/tests/wizardWorkflowRuntime.test.mjs: per-workspace mock that conflicts+holds the first save, then asserts B is untouched and A receives the running checkpoint.

The regression test fails on the old pointer (workflow-a appears in B) and passes with the pin.

Data, provenance and compatibility

No schema or file-format change. Existing workflow JSON remains valid.

Files and ownership

• ui/src/features/agent/wizardWorkflowRuntime.ts — persist/open race fix.
• ui/tests/wizardWorkflowRuntime.test.mjs — regression coverage.
• Conversation persistence (wizardConversationPersistence.ts) was left untouched; that path already pins writes.

Validation

• Focused UI tests: cd ui && npx tsx --tsconfig tsconfig.app.json --import ./tests/setupI18n.ts --test tests/wizardWorkflowRuntime.test.mjs tests/rhythmic3dWorkflow.test.mjs tests/wizardConversationPersistence.test.mjs — 33 passed, 0 failed
• Confirmed the new test fails on the unfixed persist (destination store gains workflow-a) and passes after the pin
• git diff --check — clean
• python scripts/verify_clean_repo.py — N/A (no Python changes)
• python -m compileall — N/A
• cd ui && npm run i18n:check — N/A (no copy changes)
• cd ui && npm run lint -- --max-warnings=0 — not rerun; edited files have no linter errors
• cd ui && npm run build — N/A (logic-only, covered by unit tests)
• E2E/smoke checks: N/A (race is unit-tested with a deterministic hold/conflict mock)

Code quality

• Score: pending CI
• Complexity trend: pending CI
• Production LOC trend: pending CI
• Regression versus main: pending CI
• Ratchet: pending CI

CI and review

• CI: pending
• Cursor/Bugbot: pending
• Human review: pending

Coste de la tarea

• Tests simulados: 0 tokens externos
• Tests reales: N/A
• Llamadas LLM externas: 0
• Tokens de prompt: N/A
• Tokens de respuesta: N/A
• Tokens totales: N/A
• Generaciones de imágenes/audio/vídeo: 0
• Tiempo transcurrido: N/A
• Proveedores/modelos: N/A

Notes and limitations

• The first save(this.workspace, snapshot) already captured the workspace argument; the corrupt write happens on the conflict retry after open() rebinds the pointer. The test forces that retry.
• A late emit of the source workflow after switch is ignored by the panel (isWizardConversationWriteCurrent).
• Alpha flattening on Tools image upscale (RGBA → RGB) was reviewed and not included: it is the existing wgp.convert_image pipeline, not a cross-workspace data-loss bug.

Follow-up work

None required for this race. Optional later: serialize persist() globally so two workflows cannot CAS-conflict on the same collection.

Checklist

• The executive summary is understandable without reading the code.
• The detailed Summary/Overview has not been removed or shortened.
• Tests and their actual results are recorded.
• Generated assets, secrets and local-only files are not committed.
• Required CI and Cursor/Bugbot review are complete, or the PR is clearly marked as waiting for them.